IRIX Base Documentation 2002 November

home *** CD-ROM | disk | FTP | other *** search

/ IRIX Base Documentation 2002 November / SGI IRIX Base Documentation 2002 November.iso / usr / share / catman / p_man / cat3 / c++ / ios.z / ios

Wrap

Text File | 2002-10-03 | 25.2 KB | 498 lines

IOS(3C) Last changed: 9-21-98 NNAAMMEE iiooss - Input/output formatting SSYYNNOOPPSSIISS #include <iostream.h> class ios { public: enum io_state { goodbit=0, eofbit, failbit, badbit }; enum open_mode { in, out, ate, app, trunc, nocreate, noreplace }; enum seek_dir { beg, cur, end }; /* flags for controlling format */ enum { skipws=01, left=02, right=04, internal=010, dec=020, oct=040, hex=0100, showbase=0200, showpoint=0400, uppercase=01000, showpos=02000, scientific=04000, fixed=010000, unitbuf=020000, stdio=040000 }; static const long basefield; /* dec|oct|hex */ static const long adjustfield; /* left|right|internal */ static const long floatfield; /* scientific|fixed */ public: ios(streambuf*); int bad(); static long bitalloc(); void clear(int state =0); int eof(); int fail(); char fill(); char fill(char); long flags(); long flags(long); int good(); long& iword(int); int operator!(); operator void*(); int precision(); int precision(int); streambuf* rdbuf(); void* & pword(int); int rdstate(); long setf(long setbits, long field); long setf(long); static void sync_with_stdio(); ostream* tie(); ostream* tie(ostream*); long unsetf(long); int width(); int width(int); static int xalloc(); protected: ios(); init(streambuf*); private: ios(ios&); void operator=(ios&) ; }; /* Manipulators */ ios& dec(ios&) ; ios& hex(ios&) ; ios& oct(ios&) ; ostream& endl(ostream& i) ; ostream& ends(ostream& i) ; ostream& flush(ostream&) ; istream& ws(istream&) ; IIMMPPLLEEMMEENNTTAATTIIOONN IRIX systems DDEESSCCRRIIPPTTIIOONN The stream classes derived from class iiooss provide a high level interface that supports transferring formatted and unformatted information into and out of a ssttrreeaammbbuuff. This manual page describes the operations common to both input and output. Several enumerations are declared in class iiooss, ooppeenn__mmooddee, iioo__ssttaattee, sseeeekk__ddiirr, and format flags, to avoid polluting the global name space. iioo__ssttaattee is described on this manual page under ``Error States.'' The format fields are also described on this page, under ``Formatting.'' ooppeenn__mmooddee is described in detail in ffssttrreeaamm(3C) under ooppeenn(()). sseeeekk__ddiirr is described in ssbbuuff..ppuubb(3C) under sseeeekkooffff(()). The following assumptions are made in the descriptions on this man page: * _s and _s_2 are iiooss classes. * _s_r is an iiooss&&. * _s_p is an iiooss**. * _i, _o_i, _j, and _n are iinntt addresses. * _l, _f, and _b are lloonngg addresses. * _c and _o_c are cchhaarr addresses. * _o_s_p and _o_o_s_p are oossttrreeaamm** addresses. * _s_b is a ssttrreeaammbbuuff**. * _p_o_s is a ssttrreeaammppooss. * _o_f_f is a ssttrreeaammooffff. * _d_i_r is a sseeeekk__ddiirr. * _m_o_d_e is an iinntt representing an ooppeenn__mmooddee. * _f_c_t is a function with type iiooss&& ((**))((iiooss&&)). * _v_p is a vvooiidd**&&. CCoonnssttrruuccttoorrss aanndd aassssiiggnnmmeenntt:: iiooss((_s_b)) The ssttrreeaammbbuuff denoted by _s_b becomes the ssttrreeaammbbuuff associated with the constructed iiooss. If _s_b is null, the effect is undefined. ios(sr) s2=s Copying of iioosss is not well-defined in general, therefore, the constructor and assignment operators are private so that the compiler will complain about attempts to copy iiooss objects. Copying pointers to iioossttrreeaamm classes is usually what is desired. ios() init(sb) Because class iiooss is now inherited as a virtual base class, a constructor with no arguments must be used. This constructor is declared protected. Therefore, iiooss::::iinniitt((ssttrreeaammbbuuff**)) is declared protected and must be used for initialization of derived classes. EErrrroorr SSttaatteess Class iiooss has an internal _e_r_r_o_r _s_t_a_t_e (which is a collection of the bits declared as iioo__ssttaattee classes). Members related to the error state are: _i==_s..rrddssttaattee(()) Returns the current error state. _s..cclleeaarr((_i)) Stores _i as the error state. If _i is zero, this clears all bits. To set a bit without clearing previously set bits requires something like _s..cclleeaarr((iiooss::::bbaaddbbiitt||ss..rrddssttaattee(()))). _i==_s..ggoooodd(()) Returns non-zero if the error state has no bits set, zero otherwise. _i==_s..eeooff(()) Returns non-zero if eeooffbbiitt is set in the error state, zero otherwise. Normally this bit is set when an end-of-file has been encountered during an extraction. _i==_s..ffaaiill(()) Returns non-zero if either bbaaddbbiitt or ffaaiillbbiitt is set in the error state, zero otherwise. Normally this indicates that some extraction or conversion has failed, but the stream is still usable. That is, once the ffaaiillbbiitt is cleared, I/O on _s can usually continue. _i==_s..bbaadd(()) Returns non-zero if bbaaddbbiitt is set in the error state, zero otherwise. This usually indicates that some operation on _s..rrddbbuuff(()) _h_a_s _f_a_i_l_e_d, _a _s_e_v_e_r_e _e_r_r_o_r, _f_r_o_m _w_h_i_c_h _r_e_c_o_v_e_r_y _i_s _p_r_o_b_a_b_l_y _i_m_p_o_s_s_i_b_l_e. _T_h_a_t _i_s, _i_t _w_i_l_l _p_r_o_b_a_b_l_y _b_e _i_m_p_o_s_s_i_b_l_e _t_o _c_o_n_t_i_n_u_e _I/_O _o_p_e_r_a_t_i_o_n_s _o_n _s. OOppeerraattoorrss Two operators are defined to allow convenient checking of the error state of an iiooss: ooppeerraattoorr!!(()) and ooppeerraattoorr vvooiidd**(()). The latter converts an iiooss to a pointer so that it can be compared to zero. The conversion will return 0 if ffaaiillbbiitt or bbaaddbbiitt is set in the error state, and will return a pointer value otherwise. This pointer is not meant to be used. This allows you to write expressions such as the following: if ( cin ) ... if ( cin >> x ) ... The !! operator returns non-zero if ffaaiillbbiitt or bbaaddbbiitt is set in the error state, which allows expressions like the following to be used: if ( !cout ) ... FFoorrmmaattttiinngg An iiooss has a _f_o_r_m_a_t _s_t_a_t_e that is used by input and output operations to control the details of formatting operations. For other operations, the format state has no particular effect, and its components may be set and examined arbitrarily by user code. Most formatting details are controlled by using the ffllaaggss(()), sseettff(()), and uunnsseettff(()) functions to set the following flags, which are declared in an enumeration in class iiooss. Three other components of the format state are controlled separately with the ffiillll(()), wwiiddtthh(()), and pprreecciissiioonn(()) functions. sskkiippwwss If sskkiippwwss is set, whitespace will be skipped on input. This applies to scalar extractions. When sskkiippwwss is not set, whitespace is not skipped before the extractor begins conversion. If sskkiippwwss is not set and a zero length field is encountered, the extractor will signal an error. Additionally, the arithmetic extractors will signal an error if sskkiippwwss is not set and a whitespace is encountered. lleefftt rriigghhtt iinntteerrnnaall These flags control the padding of a value. When lleefftt is set, the value is left-adjusted (the fill character is added after the value). When rriigghhtt is set, the value is right-adjusted (the fill character is added before the value). When iinntteerrnnaall is set, the fill character is added after any leading sign or base indication, but before the value. Right-adjustment is the default if none of these flags is set. These fields are collectively identified by the static member, iiooss::::aaddjjuussttffiieelldd. The fill character is controlled by the ffiillll(()) function, and the width of padding is controlled by the wwiiddtthh(()) function. ddeecc oocctt hheexx These flags control the conversion base of a value. The conversion base is 10 (decimal) if ddeecc is set, but if oocctt or hheexx is set, conversions are done in octal or hexadecimal, respectively. If none of these is set, insertions are in decimal, but extractions are interpreted according to the C++ lexical conventions for integral constants. These fields are collectively identified by the static member, iiooss::::bbaasseeffiieelldd. The manipulators hheexx, ddeecc, and oocctt can also be used to set the conversion base; see ``Built-in Manipulators'' on this man page. sshhoowwbbaassee If sshhoowwbbaassee is set, insertions will be converted to an external form that can be read according to the C++ lexical conventions for integral constants. sshhoowwbbaassee is unset by default. sshhoowwppooss If sshhoowwppooss is set, then a ++ will be inserted into a decimal conversion of a positive integral value. uuppppeerrccaassee If uuppppeerrccaassee is set, then an uppercase XX will be used for hexadecimal conversion when sshhoowwbbaassee is set, or an uppercase EE will be used to print floating point numbers in scientific notation. sshhoowwppooiinntt If sshhoowwppooiinntt is set, trailing zeros and decimal points appear in the result of a floating point conversion. sscciieennttiiffiicc ffiixxeedd These flags control the format to which a floating point value is converted for insertion into a stream. If sscciieennttiiffiicc is set, the value is converted using scientific notation, where there is one digit before the decimal point and the number of digits after it is equal to the pprreecciissiioonn (see below), which is six by default. An uppercase EE will introduce the exponent if uuppppeerrccaassee is set, a lowercase ee will appear otherwise. If ffiixxeedd is set, the value is converted to decimal notation with pprreecciissiioonn digits after the decimal point, or six by default. If neither sscciieennttiiffiicc nor ffiixxeedd is set, then the value will be converted using either notation, depending on the value; scientific notation will be used if the exponent resulting from the conversion is less than -4 or greater than or equal to precision digits. Otherwise the value will be converted to decimal notation with pprreecciissiioonn digits total. If sshhoowwppooiinntt is not set, trailing zeroes are removed from the result and a decimal point appears only if it is followed by a digit. sscciieennttiiffiicc and ffiixxeedd are collectively identified by the static member iiooss::::ffllooaattffiieelldd. uunniittbbuuff When set, a flush is performed by oossttrreeaamm::::oossffxx(()) after each insertion. Unit buffering provides a compromise between buffered output and unbuffered output. Performance is better under unit buffering than unbuffered output, which makes a system call for each character output. Unit buffering makes a system call for each insertion operation, and doesn't require the user to call oossttrreeaamm::::fflluusshh(()). ssttddiioo When set, ssttddoouutt and ssttddeerrrr are flushed by oossttrreeaamm::::oossffxx(()) after each insertion. The following functions use and set the format flags and variables. _o_c==_s..ffiillll((_c)) Sets the ``fill character'' format state variable to _c and returns the previous value. _c will be used as the padding character, if one is necessary (see the wwiiddtthh() description). The default fill or padding character is a space. The positioning of the fill character is determined by the rriigghhtt, lleefftt, and iinntteerrnnaall flags. A parameterized manipulator, sseettffiillll, is also available for setting the fill character; see mmaanniipp(3C). _c==_s..ffiillll(()) Returns the ``fill character'' format state variable. _l==_s..ffllaaggss(()) Returns the current format flags. _l==_s..ffllaaggss((ff)) Resets all the format flags to those specified in _f and returns the previous settings. _o_i==_s..pprreecciissiioonn((_i)) Sets the pprreecciissiioonn format state variable to _i and returns the previous value. This variable controls the number of significant digits inserted by the floating point inserter. The default is 6. A parameterized manipulator, sseettpprreecciissiioonn, is also available for setting the precision; see mmaanniipp(3C). _i==_s..pprreecciissiioonn(()) Returns the pprreecciissiioonn format state variable. _l==_s..sseettff((_b)) Turns on in _s the format flags marked in _b and returns the previous settings. A parameterized manipulator, sseettiioossffllaaggss, performs the same function; see mmaanniipp(3C). _l==_s..sseettff((_b,,_f)) Resets in _s only the format flags specified by _f to the settings marked in _b, and returns the previous settings. That is, the format flags specified by _f are cleared in _s, then reset to be those marked in _b. For example, to change the conversion base in _s to be hheexx, one could write: _s..sseettff((iiooss::::hheexx,,iiooss::::bbaasseeffiieelldd)). iiooss::::bbaasseeffiieelldd specifies the conversion base bits as candidates for change, and iiooss::::hheexx specifies the new value. _s..sseettff((00,,_f)) _w_i_l_l _c_l_e_a_r _a_l_l _t_h_e _b_i_t_s _s_p_e_c_i_f_i_e_d _b_y _f, _a_s _w_i_l_l _a _p_a_r_a_m_e_t_e_r_i_z_e_d _m_a_n_i_p_u_l_a_t_o_r, rreesseettiioossffllaaggss; _s_e_e mmaanniipp(_3_C). _l==_s..uunnsseettff((_b)) Unsets in _s the bits set in _b and returns the previous settings. _o_i==_s..wwiiddtthh((_i)) Sets the _f_i_e_l_d _w_i_d_t_h format variable to _i and returns the previous value. When the field width is zero (the default), inserters will insert only as many characters as necessary to represent the value being inserted. When the field width is non-zero, the inserters will insert at least that many characters, using the fill character to pad the value, if the value being inserted requires fewer than _f_i_e_l_d-_w_i_d_t_h characters to be represented. However, the numeric inserters never truncate values, so if the value being inserted will not fit in _f_i_e_l_d- _w_i_d_t_h characters, more than _f_i_e_l_d-_w_i_d_t_h characters will be output. The field width is always interpreted as a mininum number of characters; there is no direct way to specify a maximum number of characters. The _f_i_e_l_d-_w_i_d_t_h format variable is reset to the default (zero) after each insertion or extraction, and in this sense it behaves as a parameter for insertions and extractions. A parameterized manipulator, sseettww, is also available for setting the width; see mmaanniipp(3C). _i==_s..wwiiddtthh(()) Returns the _f_i_e_l_d-_w_i_d_t_h format variable. UUsseerr--ddeeffiinneedd FFoorrmmaatt FFllaaggss Class iiooss can be used as a base class for derived classes that require additional format flags or variables. The iostream library provides several functions to do this. The two static member functions iiooss::::xxaalllloocc and iiooss::::bbiittaalllloocc, allow several such classes to be used together without interference. _b==iiooss::::bbiittaalllloocc(()) Returns a lloonngg with a single, previously unallocated, bit set. This allows users who need an additional flag to acquire one, and pass it as an argument to iiooss::::sseettff(()), for example. _i==iiooss::::xxaalllloocc(()) Returns a previously unused index into an array of words available for use as format state variables by derived classes. _l==_s..iiwwoorrdd((_i)) When _i is an index allocated by iiooss::::xxaalllloocc, iiwwoorrdd(()) returns a reference to the _ith user-defined word. _v_p==_s..ppwwoorrdd((_i)) When _i is an index allocated by iiooss::::xxaalllloocc, ppwwoorrdd(()) returns a reference to the _ith user-defined word. ppwwoorrdd(()) is the same as iiwwoorrdd except that it is typed differently. OOtthheerr mmeemmbbeerrss:: _s_b==_s..rrddbbuuff(()) Returns a pointer to the ssttrreeaammbbuuff associated with _s when _s was constructed. iiooss::::ssyynncc__wwiitthh__ssttddiioo(()) Solves problems that arise when mixing stdio and iostreams. The first time it is called it will reset the standard iostreams (cciinn, ccoouutt, cceerrrr, cclloogg) to be streams using ssttddiioobbuuffs. After that, input and output using these streams may be mixed with input and output using the corresponding FFIILLEEs (ssttddiinn, ssttddoouutt, and ssttddeerrrr) and will be properly synchronized. ssyynncc__wwiitthh__ssttddiioo(()) makes ccoouutt and cceerrrr unit buffered (see iiooss::::uunniittbbuuff and iiooss::::ssttddiioo above). Invoking ssyynncc__wwiitthh__ssttddiioo(()) degrades performance a variable amount, depending on the length of the strings being inserted (shorter strings incur a larger performance hit). _o_o_s_p==_s..ttiiee((_o_s_p)) Sets the ttiiee variable to _o_s_p, and returns its previous value. This variable supports automatic ``flushing'' of iioosss. If the ttiiee variable is non-null and an iiooss needs more characters or has characters to be consumed, the iiooss pointed at by the tie variable is flushed. By default, cciinn is tied initially to ccoouutt so that attempts to get more characters from standard input result in flushing standard output. Additionally, cceerrrr and cclloogg are tied to ccoouutt by default. For other iioosss, the tie variable is set to zero by default. _o_s_p==_s..ttiiee(()) Returns the ttiiee variable. BBuuiilltt--iinn MMaanniippuullaattoorrss:: Some convenient manipulators (functions that take an iiooss&&, an iissttrreeaamm&&, or an oossttrreeaamm&& and return their argument; see mmaanniipp(3C)) are: _s_r<<<<ddeecc _s_r>>>>ddeecc These set the conversion base format flag to 10. _s_r<<<<hheexx _s_r>>>>hheexx These set the conversion base format flag to 16. _s_r<<<<oocctt _s_r>>>>oocctt These set the conversion base format flag to 8. _s_r>>>>wwss Extracts whitespace characters. See iissttrreeaamm(3C). _s_r<<<<eennddll Ends a line by inserting a newline character and flushing. See oossttrreeaamm(3C). _s_r<<<<eennddss Ends a string by inserting a null (0) character. See oossttrreeaamm(3C). _s_r<<<<fflluusshh Flushes oouuttss. See oossttrreeaamm(3C). Several parameterized manipulators that operate on iiooss objects are described in mmaanniipp(3C): sseettww, sseettffiillll, sseettpprreecciissiioonn, sseettiioossffllaaggss, and rreesseettiioossffllaaggss. The ssttrreeaammbbuuff associated with an iiooss may be manipulated by other methods than through the iiooss. For example, characters may be stored in a queuelike ssttrreeaammbbuuff through an oossttrreeaamm while they are being fetched through an iissttrreeaamm. Or for efficiency some part of a program may choose to do ssttrreeaammbbuuff operations directly rather than through the iiooss. In most cases the program does not have to worry about this possibility, because an iiooss never saves information about the internal state of a ssttrreeaammbbuuff. For example, if the ssttrreeaammbbuuff is repositioned between extraction operations the extraction (input) will proceed normally. NNOOTTEESS The old stream package called ssyynncc__wwiitthh__ssttddiioo as a default, but in the iostream package, unbuffered ssttddiioobbuuffs are too inefficient to be the default. The stream package had a constructor that took a FFIILLEE** argument. This is now replaced by ssttddiioossttrreeaamm. It is not declared even as an obsolete form to avoid having iioossttrreeaamm..hh depend on ssttddiioo..hh. The old stream package allowed copying of streams. This is disallowed by the iostream package. However, objects of type iissttrreeaamm__wwiitthhaassssiiggnn, oossttrreeaamm__wwiitthhaassssiiggnn, and iioossttrreeaamm__wwiitthhaassssiiggnn can be assigned to. Old code using copying can usually be rewritten to use pointers or these classes. (The standard streams cciinn, ccoouutt, cceerrrr, and cclloogg are members of wwiitthhaassssiiggnn classes, so they can be assigned to, as in cciinn == iinnppuuttffssttrreeaamm.) SSEEEE AALLSSOO iioossttrreeaamm(3C), ssttrreeaammbbuuff(3C), iissttrreeaamm(3C), oossttrreeaamm(3C), mmaanniipp(3C) This man page is available only online.